Readme file for the JPEG Component Library
==========================================

This file contains documentation for the JPEG Component Library by MWA Software. 
This documentation is subject to further update. For further information please 
contact MWA Software - mailto:sales@mwassocs.demon.co.uk. 

ONLINE HELP IS ALSO AVAILABLE IN THE FILE mwjpeg.hlp.

This file contains the following information:

1. ABOUT THE COMPONENT LIBRARY
2. INSTALLATION INSTRUCTIONS
3. USING THE JPEG DEMO APPLICATION
4. PRELIMINARY SOFTWARE DOCUMENTATION
5. PRICING INFORMATION
6. HOW TO REGISTRATION
7. SECURE REGISTRATION

1. ABOUT THE COMPONENT LIBRARY
==============================

The JPEG Component Library provides two additional non-visual components for use 
under either Delphi 1.0 or Delphi 2.0. These are TJPEGFileCompressor and 
TJPEGFileDecompressor. These support compression of images to JPEG Format and 
decompression respectively.  This, the shareware version comes with a licence to 
evaluate for 30 days, after which you must register (see below) in order to 
continue to use the software. The shareware version will only operate while the 
Delphi IDE is active.

Simply installing these components JPEG enables the Delphi IDE. The components 
register themselves as supporting .jpg files and the JPEG compression format and, 
when you come to load an image into a TImage Picture, the JPEG format will be 
found amongst the list of supported file formats. An image loaded from a JPEG 
source can also be saved back to JPEG. These components support the JPEG File 
Interchange Format (JFIF).

These two components also support TImage at run-time too. As at design time, if 
TJPEGFileDecompressor is included in your project, then calling 
TImage.Picture.LoadFromFile when the file extension is .jpg will automatically 
invoke the JPEG decompressor. You can also explicitly call TJPEGFileDecompressor 
to load a JPEG image from any file.

TJPEGFileCompressor can be used to save a TImage.Picture in JPEG format, and can 
handle pictures that are either bitmaps or metafiles. It can also compress a 
device independent bitmap.

This software uses original software for JPEG developed by the Independent JPEG 
Group (see ftp://ftp.uu.net/graphics/jpeg). The IDG have made available a library 
of generic 'C' code supporting JPEG compression and decompression and have 
permitted its free use provided the source is acknowledged. The IDG code has been 
modified for use with Delphi and MS Windows and is provided as a separate .dll 
(mwjpeg.dll for the 16-bit version and mwjpeg32.dll for the 32-bit version). This 
dll may be freely distributed.

An interface to this .dll is provided by the unit jpeglib.pas. This is 
encapsulated as a set of Delphi components in the unit jpeg.pas, which also 
supports the mapping of the environment independent image format expected by the 
IJG code into MS Windows bitmap and metafile formats.

When you purchase a licence to this product, you purchase a licence for the source 
code to the jpeg and jpeglib units and the right to include binaries derived from 
them in your own products without having to pay additional royalties. You also 
have a right to freely distribute the mwjpeg and mwjpeg32 dlls, and copies of the 
modified 'C' source is also included in the registered version. Support is also 
provided by EMail albeit without a guaranteed response time.

2. INSTALLATION INSTRUCTIONS
============================

Installation is straightforward. The JPEG Component Library is distributed in a 
.zip archive, with one version for use with Delphi 1.0 and the other for Delphi 
2.0. Make sure you have the correct version and then:

i. Copy the jpeg .dll to your windows directory. This will be mwjpeg.dll for 
Delphi 1.0 and mwjpeg32.dll for Delphi 2.0.

ii. Create a new sub-directory in your delphi directory (the actual name is 
unimportant - call it jpeg if you can't think of anything better) and copy the 
remaining files contained in the .zip file into this new subdirectory.

iii. Start the Delphi IDE and choose then Options|Install Components (Delphi 1.0) 
or Component|Install (Delphi 2.0) menu option. Click on the "Add" button and 
browse for the jpeg-reg.pas file you just copied to the new subdirectory. Click on 
OK. (Note that this file contains the registration information for the JPEG 
components. By default these are placed on the "Additional" tab. You can edit this 
file to locate them elsewhere).

The components are now installed. Use the demo application to learn how they are 
used.

3. USING THE JPEG DEMO APPLICATION
==================================

The JPEG Demo application may be found in the subdirectory created above. To 
activate, load the jpegdemo.dpr file into the IDE using the File|Open Project 
(Delphi 1.0) or the File|Open (Delphi 2.0) menu item. This provides a simple 
application that can open and save .jpg (JPEG), .bmp (Windows Bitmap) and .wmf 
(Windows metfaile) files, and copy and paste bitmaps and metafiles to and from the 
clipboard. To test out, simply compile and run the application.

To load and view a JPEG file, click on the open button and load the test.jpg file 
contained in the subdirectory created above. You can also try saving it to another 
file name (you can save it as either a JPEG or a bitmap). You can also use the 
demo application to convert windows bitmaps and metafiles to jpegs simply by 
opening the file containing them (or pasting from the clipboard) and saving them 
as jpegs.

You can also use the Object Inspector to see the properties published by the two 
JPEG components.

4. PRELIMINARY SOFTWARE DOCUMENTATION
=====================================

TJPEGFileCompressor
------------------

Properties:

Comment: string

This comment is included in the compressed JPEG image. A typical use is to include 
a copyright message.

DCTMethod: J_DCT_METHOD;

Selects the algorithm used for the DCT quantisation step.  Choices are:
	JDCT_ISLOW: slow but accurate integer algorithm
	JDCT_IFAST: faster, less accurate integer method
	JDCT_FLOAT: floating-point method
The FLOAT method is very slightly more accurate than the ISLOW method, but may 
give different results on different machines due to varying roundoff behaviour.  
The integer methods should give the same results on all machines.  On machines 
with sufficiently fast FP hardware, the floating-point method may also be the 
fastest.  The IFAST method is considerably less accurate than the other two; its 
use is not recommended if high quality is a concern.  

DensityUnit: UINT8;
X_Density: UNIT16;
Y_Density: UNIT16;

The resolution information to be written into the JFIF marker; not used otherwise.  
density_unit may be 0 for unknown, 1 for dots/inch, or 2 for dots/cm.  The default 
values are 0,1,1 indicating square pixels of unknown size.

GrayscaleOutput: boolean;

If true then the image is converted to a grayscale image when written out to the 
JPEG file.

OptimizeCoding: boolean;

TRUE causes the compressor to compute optimal Huffman coding tables for the image.  
This requires an extra pass over the data and therefore costs a good deal of space 
and time.  The default is FALSE, which tells the compressor to use the supplied or 
default Huffman tables.  In most cases optimal tables save only a few percent of 
file size compared to the default tables.  

ProgressiveJPEG: boolean;

Progressive JPEG rearranges the stored data into a series of scans of increasing 
quality.  In situations where a JPEG file is transmitted across a slow 
communications link, a decoder can generate a low-quality image very quickly from 
the first scan, then gradually improve the displayed quality as more scans are 
received.  The final image after all scans are complete is identical to that of a 
regular (sequential) JPEG file of the same quality setting.  Progressive JPEG 
files are often slightly smaller than equivalent sequential JPEG files, but the 
possibility of incremental display is the main reason for using progressive JPEG.

When this property is set to true a progressive JPEG file is generated using a 
default scan script generated by the JPEG library.

Quality: int;

JPEG quantisation tables appropriate for the indicated quality setting are 
generated.  The quality value is expressed on a 0..100 scale. 

RestartInterval: Cardinal;
RestartInRows: int;

To emit restart markers in the JPEG file, set one of these nonzero. Set 
RestartInterval to specify the exact interval in MCU blocks. Set RestartInRows to 
specify the interval in MCU rows.  (If RestartInRows is not 0, then 
RestartInterval is set after the image width in MCUs is computed.)  Defaults are 
zero (no restarts).


Smoothing Factor: int;

If non-zero, the input image is smoothed; the value should be 1 for minimal 
smoothing to 100 for maximum smoothing.  The default is zero.

Trace_Level: int;

Controls the level of trace information reported. (set >= 3 to see more than the 
first warning message).

WriteAllTables: boolean;

Set to True (default) to ensure that a proper JPEG Interchange stream is written. 
If false, then the quantisation and Huffman tables are not written to the JPEG 
file. This makes for a smaller file but creates difficulties for the decompressor 
unless some other way is found to transfer these tables.

WriteJFIFHeader: boolean;

If true (default) then a JFIF APP0 marker is emitted. The decompressor will then 
recognise it as a JFIF compatible stream.


Methods:

procedure SavePictureToFile(Picture: TPicture; const FileName: string);

Provided that the Picture holds a Bitmap or a Metafile image, it will be 
compressed to a JPEG and written out to the file "FileName".

procedure SavePictureToStream(Picture: TPicture; Stream: TStream);

Provided that the Picture holds a Bitmap or a Metafile image, it will be 
compressed to a JPEG and written out to the provided stream.

procedure SaveBitMapToStream(bitmap: TBitmap; Stream: TStream);

The bitmap is compressed to a JPEG and written out to the provided stream.

procedure SaveDIBitmapToStream(Stream: TStream; const BitmapInfo: TBitmapInfo;
                                bits: PChar);

The device independent bitmap held in the memory block given by "bits", is 
compressed to a JPEG and written out to the provided stream. Note that the 
BitmapInfo structure is defined by the Windows API and defines the size and 
resolution of the bitmap and may also contain a colour map.

procedure SaveMetaFileToStream(metafile: TMetafile; Stream: TStream; width, 
height: longint);

The metafile is compressed to a JPEG and written out to the provided stream. Note 
that the height and width of the required image (in pixels) must also be provided.

procedure WriteMarker(Marker: int; const buf; Count: uint);

This method may be called from the event "OnWriteMarkers" to write out data with a 
JPEG APPn marker. The actual marker is identified by the Marker parameter (e.g. to 
write out an APP1 marker, set Marker to one). The value data written out is 
contained in buf and contains Count bytes.

Events:

OnProgessReport: TNotifyEvent

Called regularly during compression to enable a progress report to be maintained. 
The PercentDone integer property (read only) may be consulted to find out the 
percentage so far compressed.

OnWriteMarkers: TNotifyEvent

See above discussion of WriteMarker Method.

TJPEGFileDecompressor
---------------------

Properties:

DCTMethod: J_DCT_METHOD;

Selects the algorithm used for the DCT quantisation step.  Choices are as for 
compression.

DitherMode: J_DITHER_MODE 

Selects color dithering method.  Supported values are:

	JDITHER_NONE	no dithering: fast, very low quality
	JDITHER_ORDERED	ordered dither: moderate speed and quality
	JDITHER_FS	Floyd-Steinberg dither: slow, high quality

Default is JDITHER_FS.  (At present, ordered dither is implemented only in the 
single-pass, standard-colormap case.  If you ask for ordered dither when 
two_pass_quantize is TRUE or when you supply an external color map, you'll get F-S 
dithering.)

DoBlockSmoothing: boolean

If TRUE, interblock smoothing is applied in early stages of decoding progressive 
JPEG files; if FALSE, not.  Default is TRUE.  Early progression stages look 
"fuzzy" with smoothing, "blocky" without. 

DoFancyUpSampling: boolean

If TRUE, do careful upsampling of chroma components.  If FALSE, a faster but 
sloppier method is used.  Default is TRUE.  The visual impact of the sloppier 
method is often very small.

GrayScaleOutput: boolean

If true then the image is converted to a 64 level grayscale image on decoding.

TwoPassQuantize: boolean

If TRUE, an extra pass over the image is made to select a custom colour map for 
the image.  This usually looks a lot better than the one-size-fits-all colourmap 
that is used otherwise.  Default is TRUE.  Ignored when the application supplies 
its own colour map.

Trace_Level: int;

Controls the level of trace information reported. (set >= 3 to see more than the 
first warning message).

Methods:

procedure LoadPictureFromFile(Picture: TPicture; const FileName: string);

Opens the file identified by FileName which is assumed to contain a JPEG image in 
the JFIF format. This is decoded into a windows bitmap and loaded into the 
supplied Picture object.


procedure ConvertToDIB(Source, Destination: TStream; OutputType: TJPEGOutputType);

Converts a JPEG compressed image Windows Device Independent bitmap contained in 
the Source stream to a Windows Device Independent bitmap written to the 
destination stream.

The format of the DIB is determined by the setting of OutputType. This may be 
either:

  TJPEGOutputType = (jp24bit, {24 bit bitmap}
		     jp8bit,  {256 colour bitmap}
		     jp4bit,  {16 colour bitmap} 
		     jpGrayscale); {grayscale}


procedure LoadPictureFromStream(Picture: TPicture; Stream: TStream);

The source stream is assumed to contain a JPEG image in the JFIF format. This is 
decoded into a windows bitmap and loaded into the supplied Picture object.

function ReadBitMapFromStream(Stream: TStream): TBitmap;

The source stream is assumed to contain a JPEG image in the JFIF format. This is 
decoded into a windows bitmap and returned as a TBitmap object.


procedure ReadDIBitmapFromStream(Stream: TStream;
                                       var BitMapInfo: TBitMapInfo;
                                       OutputType: TJPEGOutputType;
                                       var bits: THandle);

The source stream is assumed to contain a JPEG image in the JFIF format. This is 
decoded into a windows device independent bitmap and returned in the memory block 
given by bits. The output type is determined as above and the information 
describing the bitmap size, resolution and colour map is returned in the Windows 
APS BitMapInfo structure. 

Events:

OnJPEGComment: TJPEGCommentEvent

  TJPEGCommentEvent = procedure(sender: TJPEGBase; comment: PChar) of object;

This event occurs when a comment is found in the JPEG compressed image. The 
comment is extracted and provided as a parameter to the event handler.

OnJPEGMarker: TJPEGMarkerEvent

  TJPEGMarkerEvent = procedure(sender: TJPEGBase; Marker: int; var Done: boolean) 
of object;

This event occurs when any other JPEG marker is found in the JPEG image (except 
for APP1 the JFIF marker). The marker is identified by the Marker parameter (range 
1..13), and the response method may read successive bytes from the stream after 
the marker by calling the GetByte method (this is a parameterless function that 
returns a single byte value). Note that marker processing is application specific.

If the marker is not processed, then the response method should return with Done 
set to false. The marker text will then be skipped, otherwise, Done should be set 
to true to indicate that the response method has handled the marker itself.

OnProgessReport: TNotifyEvent

Called regularly during compression to enable a progress report to be maintained. 
The PercentDone integer property (read only) may be consulted to find out the 
percentage so far compressed.

5. PRICING INFORMATION
======================

JPEG Component Library Source Licence        12 pounds sterling (US$20)

US dollar prices are for indicative pricing only and assume an exchange rate of 
one pound = $1.66.  All prices are VAT exclusive. UK VAT (currently 17.5%) will be 

charged for all UK residents and EC residents that are not VAT registered or do 
provide a VAT number as proof of registration.


6. HOW TO REGISTER
==================

Registration may be made by FAX, Letter Post or EMail. For FAX and Letter Post 
registrations, a Registration Form is provided in the File "regform.txt" for you 
to EMail or  print out (FAX or letter post), complete, and send to MWA Software. 
You can also register using the Compuserve Shareware Registration Service (GO 
SWREG). The software is registered under the name "MWA JPEG Component Library".

Visa, Mastercard, Eurocard and JCB are accepted as payment mechanisms. 
International money orders in pounds sterling and cheques drawn on UK Bank 
Accounts are also accepted. US Dollar denominated checks are also acceptable 
provided that an additional 10% is added to the purchase price to allow for the 
additional Bank Charge. Please make cheques payable to McCallum Whyman Associates 
Ltd.

EMail registrations should be sent to:
  Internet:	sales@mwassocs.demon.co.uk, or 
  Compuserve:	100041,315

FAX: 
  UK: 01962 735581
  Int: +44 1962 735581

MWA Software,
P.O.Box 37,
Alresford,
Hants,
SO24 9ZF,
ENGLAND


All registrations are accepted on the basis that the registered user will be 
deemed to have accepted and be bound by the licence conditions for the registered 
versions of JPEG component library as recorded in the file reg-lnce.txt supplied 
with the evaluation version of the software.

7. Secure Registration by EMail
================================

There are two routes by which you can EMail your credit card details to MWA 
Software without incurring the risk of sending a credit card number in clear 
across the Internet. One route is to use the encryption mechanism provided by 
pkzip. The other is to use PGP.

pkzip encryption will generally be good enough to avoid detection by the so called 
"sniffer" programs that are understood to monitor EMail communications, looking 
for numbers that look like credit cards. However, it is not believe to be good 
enough to resist a determined attack by someone who has access to the necessary 
skills in cryptography and a powerful enough computer. On the other hand PGP is 
understood to offer a very strong level of protection. MWA Software makes no 
recommendations as to which is the better approach. It is for you to decide based 
on your own location and concerns.

Secure Transmission using pkzip.
================================

pkzip can encrypt files in a .zip archive using a simple password. To register for 
the JPEG Component Library by EMail when using pkzip as your encryption engine:

1. Using the file "regform.txt" as a template, complete a registration form for 
the JPEG Component Library. Remember to include your credit card details, billing 
address and your name as it appears on your credit card. 

2. Choose a password. Opening a dictionary at some random page is often a good way 
to do this. For example, let's assume that you choose NERVOUS as your password.

3. Compress and encrypt the modified regform.txt using pkzip and the -s option to 
encrypt. For example, with NERVOUS as your password, use the command line:

pkzip -sNERVOUS regform regform.txt

This will create regform.zip containing your compressed and encryted registration 
details.

4. EMail regform.zip to MWA Software. Your own EMail utility will usually have a 
way to send binary attachments to an EMail message. If you do not have such a 
capability then you can use the J-Write Text Editor (also available from MWA 
Software) to uuencode a binary file into a text form suitable for attaching to an 
EMAil message. This feature is available from the File|Merge menu item. 

The MWA Software EMail address is sales@mwassocs.demon.co.uk.
Set the subject to "JPEG Registration"

5. Send the password you choose at step 2 in a separate EMail to MWA Software. For 
best protection, use our Compuserve EMail address:

100041.315@compuserve.com

Set the subject to "re: JPEG Registration"

Secure Transmission using PGP
=============================

PGP is a powerful data encryption tool that has been made publicly available by 
its author "Phillip Zimmermann". It is sufficiently good to attract the attentions 
of various government's agency's and you should be aware that in certain countries 
the use of such encryption software is a criminal offence. MWA Software only uses 
PGP to decrypt registrations and does not send encrypted EMail. Having said that, 
the international version of PGP can be obtained from:

http://www.ifi.uio.no/pgp/

The following URL is also a good source of information about PGP, including 
information on how to get the more limited US version.

http://www.arc.unm.edu/~drosoff/pgp/pgp.html

To encrypt a registration using PGP, do the following:

1. Using the file "regform.txt" as a template, complete a registration form for 
the JPEG Component Library. Remember to include your credit card details, billing 
address and your name as it appears on your credit card. 

2. Encrypt regform.txt using PGP and the MWA public key. This is provided in the 
file "mwakey.asc", which should be in the same archive as this file. This will 
typically be performed by the following commands (the ; indicates the start of a 
comment):

pgp -ka mwakey.asc                    ;add MWA key to your public keyring
pgp -ea regform.txt "MWA Software"    ;encrypt and encode for EMail
pgp -kr "MWA Software"                ;remove the MWA key from your keyring

The above will have created the encrypted file "regform.pgp". This is a text file 
and may be sent as part of a normal EMail to MWA Software:

sales@mwassocs.demon.co.uk

Set the subject to "JPEG Registration"

If you have any reason to doubt the validity of the MWA key, request an up-to-date 
version by EMail to the above address, with a subject of "Key Verification 
Request".

Thank you for registering forthe JPEG Component Library.
